"""https://beautifulsoup.readthedocs.io/zh_CN/v4.4.0"""
# 基础

"""
将一段文档传入BeautifulSoup 的构造方法,就能得到一个文档的对象
首先,文档被转换成Unicode,并且HTML的实例都被转换成Unicode编码

Beautiful Soup将复杂HTML文档转换成一个复杂的树形结构,每个节点都是Python对象
所有对象可以归纳为4种: Tag , NavigableString , BeautifulSoup , Comment

# tag
# 对象与XML或HTML原生文档中的tag相同
# 例: print(soup.h1)
# 例: print(soup.h2)

# name
# 每个tag都有自己的名字,通过 .name 来获取
# 例: print(soup.h1.name)

# attributes
# 一个tag可能有很多个属性. tag的属性的操作方法与字典相同
# 例: soup.h1['class'] = 'aaa'
# 例: print(soup.a['class'])
# 例: print(soup.h1.attrs)
"""


# 搜索文档树 过滤器
"""
Beautiful Soup定义了很多搜索方法,这里着重介绍2个: find() 和 find_all() .
其它方法的参数和用法类似,请读者举一反三.

### 过滤器
### 过滤器可以被用在tag的name中,节点的属性中,字符串中或他们的混合中.

## 字符串
## 最简单的过滤器是字符串.
## 在搜索方法中传入一个字符串参数,Beautiful Soup会查找与字符串完整匹配的内容
# 例子: soup.find_all('b')
# 结果: [<b>The Dormouse's story</b>]

## 正则表达式
## 如果传入正则表达式作为参数, Beautiful Soup会通过正则表达式的 match() 来匹配内容
# 例子: soup.find_all(re.compile("^b"))
# 结果: [<body></body>, <b></b>]

## 列表
## 如果传入列表参数,Beautiful Soup会将与列表中任一元素匹配的内容返回.
# 例子: soup.find_all(["a", "b"])
# 结果: [<b>The Dormouse's story</b>, <a class="sister" href="#" id="link1">Elsie</a>, <a class="sister" href="#" id="link2">Lacie</a>]

## True
## 可以匹配任何值,下面代码查找到所有的tag,但是不会返回字符串节点

## 方法
## 如果没有合适过滤器,那么还可以定义一个方法,方法只接受一个元素参数, 如果这个方法返回 True 表示当前元素匹配并且被找到. 如果不是则反回 False
# 例子: 
#   def has_class_but_no_id(tag):
#       return tag.has_attr('class') and not tag.has_attr('id')
#   soup.find_all(has_class_but_no_id)
# 结果: [<p class="title"><b>The</b></p>, <p class="story">Once</p>]
"""


# 搜索文档树 find_all() 和 find()
"""
* 使用 find_all() 类似的方法可以查找到想要查找的文档内容
* find_all() 方法搜索当前tag的所有tag子节点,并判断是否符合过滤器的条件.

* find_all() 几乎是Beautiful Soup中最常用的搜索方法, 所以我们定义了它的简写方法. BeautifulSoup 对象和 tag 对象可以被当作一个方法来使用,这个方法的执行结果与调用这个对象的 find_all() 方法相同,下面两行代码是等价的:
# soup.find_all("a")
# soup("a")

* find_all( name , attrs , recursive , string , **kwargs )
* find( name , attrs , recursive , string , **kwargs )
** find() 只返回找到的第一条


# 例子: soup.find_all("title")
# 结果: [<title>The Dormouse's story</title>]

# 例子: soup.find_all("p", "title")
# 结果: [<p class="title"><b>The Dormouse's story</b></p>]

# 例子: soup.find_all(id="link2")
# 结果: [<a class="sister" href="http://example.com/lacie" id="link2">Lacie</a>]

## name 参数
## name 参数可以查找所有名字为 name 的tag,字符串对象会被自动忽略掉.
# 例子: soup.find_all("title")
# 结果: [<title>The Dormouse's story</title>]

## keyword 参数
## 如果一个指定名字的参数不是搜索内置的参数名,搜索时会把该参数当作指定名字tag的属性来搜索,
## 如果包含一个名字为 id 的参数,Beautiful Soup会搜索每个tag的”id”属性.
# 例子: soup.find_all(id='link2')
# 结果: [<a class="sister" href="http://example.com/lacie" id="link2">Lacie</a>]
## 如果传入 href 参数,Beautiful Soup会搜索每个tag的”href”属性:
# 例子: soup.find_all(href=re.compile("elsie"))
# 结果: [<a class="sister" href="http://example.com/elsie" id="link1">Elsie</a>]
## 使用多个指定名字的参数可以同时过滤tag的多个属性:
# 例子: soup.find_all(href=re.compile("elsie"), id='link1')
# 结果: [<a class="sister" href="http://example.com/elsie" id="link1">three</a>]
## 有些tag属性在搜索不能使用,比如HTML5中的 data-* 属性
# 例子: data_soup.find_all(data-foo="value")
# 结果: SyntaxError: keyword can't be an expression
## 但是可以通过 find_all() 方法的 attrs 参数定义一个字典参数来搜索包含特殊属性的tag
# 例子: data_soup.find_all(attrs={"data-foo": "value"})
# 结果: [<div data-foo="value">foo!</div>]

## 按CSS搜索
## 按照CSS类名搜索tag的功能非常实用
## 但标识CSS类名的关键字 class 在Python中是保留字,使用 class 做参数会导致语法错误.
## 从Beautiful Soup的4.1.1版本开始,可以通过 class_ 参数搜索有指定CSS类名的tag
# 例子: soup.find_all("a", class_="sister")
# 结果: [<a class="sister" href="http://example.com/elsie" id="link1">Elsie</a>]
# 例子: soup.find_all(class_=re.compile("itl"))
# 结果: [<p class="title"><b>The Dormouse's story</b></p>]
## 搜索 class 属性时也可以通过CSS值完全匹配
## 完全匹配 class 的值时,如果CSS类名的顺序与实际不符,将搜索不到结果
# 例子: css_soup.find_all("p", class_="body strikeout")
# 结果: [<p class="body strikeout"></p>]
# 例子: css_soup.find_all("p", class_="strikeout body")
# 结果: 找不到

## string 参数 
## 通过 string 参数可以搜搜文档中的字符串内容.
## 与 name 参数的可选值一样, string 参数接受 字符串 , 正则表达式 , 列表, True . 
# 例子: soup.find_all(string="Elsie")
# 结果: [u'Elsie']
# 例子: soup.find_all(string=["Tillie", "Elsie", "Lacie"])
# 结果: [u'Elsie', u'Lacie', u'Tillie']
# 例子: soup.find_all(string=re.compile("Dormouse"))
# 结果: [u"The Dormouse's story", u"The Dormouse's story"]

## limit 参数
## find_all() 方法返回全部的搜索结构,如果文档树很大那么搜索会很慢.
## 如果我们不需要全部结果,可以使用 limit 参数限制返回结果的数量.
## 效果与SQL中的limit关键字类似,当搜索到的结果数量达到 limit 的限制时,就停止搜索返回结果.
# 例子: soup.find_all("a", limit=2)
# 结果: [<a class="sister" href="#" id="link1">Elsie</a>, <a class="sister" href="#" id="link2">Lacie</a>]

## recursive 参数
## 调用tag的 find_all() 方法时,Beautiful Soup会检索当前tag的所有子孙节点
## 如果只想搜索tag的直接子节点,可以使用参数 recursive=False .

"""
